Contents of GRAFSEC1

When writing a program that uses the Grafix library, you should include the file graf.h . This file defines prototypes for all the graphics functions and several symbolic constants. When linking, simply include the Grafix library in the list of libraries you supply to LINK. The small model library is named grafix.lib , and the medium, compact, and large model libraries are named grafixm.lib , grafixc.lib , and grafixl.lib , respectively.

Note that g_init must be the first function in the library to be called, and that g_open must be the second. When you finish with the graphics display, you should call g_close to reset the display to text mode.

IBM Enhanced Graphics Adapter (EGA) with a Enhanced Graphics Display, with a Color Display, or with a Monochrome Display or equivalents.

It should be kept in mind that the color values which are passed to the graphics routines and written into the graphics buffers correspond only indirectly to the colors actually displayed on the screen. The mapping between color values and displayed colors can be changed by the g_setback and g_setpal functions. See the ``colors(1)'' manual page for a description of the available colors. grafex1.c

colors — summary of displayable colors The following summarizes the displayable colors in the various supported graphics modes.

In this mode, color value 0 is the background. By default it is black but may be changed by use of the g_setback function to any of the following colors:

&val&ue & &value&&color

&0&& black &1&& blue &2&& green &3&& cyan &4&& red &5&& purple &6&& brown &7&& white &8&& grey &9&& bright blue &10&& bright green &11&& bright cyan &12&& bright red &13&& bright purple &14&& bright yellow &15&& bright white

&color&value &background & &color value&& $\it palette=0$ & $\it palette=1$

&& 0 &background&background && 1 &green&cyan && 2 &red&magenta && 3 &yellow&white

In this mode, color value 0 is the background and is always displayed as black. Color value 1 is the foreground and has a default color of white. This may be changed, however, with the g_setpal function to any of the colors listed as a CGA background color in the previous section.

The EGA has 64 displayable colors, 16 of which can be displayed at any time. The displayable colors are represented as a six-bit value with format rgbRGB, where the intensities of of the primary colors (red, green, and blue) are in the range 0–3 and represented as the two-bit values Rr, Gg, and Bb. The mapping of color values to these colors can be changed using the g_setpal function (or g_setback for color value 0). The default mapping is as follows:

&color &value &bright yellow &six-bit & &color value&&color&six-bit value

&0&&black&0& &1&&blue&1& &2&&green&2& &3&&cyan&3& &4&&red&4& &5&&purple&5& &6&&brown&20& &7&&white&7& &8&&grey&56& &9&&bright blue&57& &10&&bright green&58& &11&&bright cyan&59& &12&&bright red&60& &13&&bright purple&61& &14&&bright yellow&62& &15&&bright white&63&

int x1, y1, x2, y2; unsigned color; The g_box function draws the rectangular box defined by the points (x1, y1) and (x2, y2) in the current drawing buffer with color color . If xor mode is on, the rectangle will be logically xor'ed with the existing data in the buffer. g_line(1).

int x, y, r; unsigned color; The g_circle function draws a circle centered on the point (x, y) with radius r . The circle is drawn in the current drawing buffer with color color . If xor mode is on, the circle is logically xor'ed with the existing data in the buffer. The radius is taken to be half of the horizontal diameter of the circle, in pixels (because of the graphics display's aspect ratio, this will not in general be the same as the vertical radius of the circle). g_ellipse(1).

g_clear — clear the area within the clipping boundary to a given color void g_clear(color)

unsigned color; The g_clear function sets all the pixels within the current clipping boundary in the current drawing buffer to color color . g_clearall(1), g_regfill(1), g_setclip(1).

g_clearall — clear an entire buffer to a specified color void g_clearall(color)

unsigned color; The g_clearall function sets the entire current drawing buffer to color color , regardless of clipping boundaries. For clearing the entire screen, g_clearall should be somewhat faster than g_clear . g_clear(1).

g_close — terminate graphics drawing void g_close() The g_close function terminates graphics drawing and resets the display to 80-column text mode. g_init(1), g_open(1).

int x, y, r_sub_m; float aspect; unsigned color; The g_ellipse function draws an ellipse in the current drawing buffer with color color centered on the point (x, y) with semi-major axis length r_sub_m and aspect ratio aspect . The aspect ratio is defined as the ratio of the vertical diameter of the ellipse to its horizontal diameter, and the semi-major axis length is half the length of the largest diameter (which is vertical if aspect > 1.0 and horizontal if aspect < 1.0). If xor mode is on, the ellipse will be logically xor'ed with the existing data in the buffer. Note that this routine can only be used to draw ellipses that have their axes oriented horizontally and vertically. The aspect ratio of the screen is not accounted for in this routine. If you want to have an ellipse drawn in the same shape on all supported displays, get the display's aspect ratio with the g_info call and multiply your desired aspect ratio by it before passing it to g_ellipse . g_circle(1), g_info(1).

struct g_info *info; The g_info function copies parameters for the current mode and adapter into the structure info . The g_info structure is defined in the file graf.h as: struct g_info unsigned card; unsigned display; unsigned xsize, ysize; unsigned xchsize, ychsize; unsigned colormax; unsigned pages; unsigned curpage; ; Card and display contain the current types of the graphics card and the graphics display, respectively (the types are defined in graf.h ). Xsize and ysize contain the X and Y sizes of the display, xchsize and ychsize contain the size of the screen in characters, and colormax contains the maximum color value (i.e., if there are four colors, colormax will be 3). Pages contains the number of displayable pages that the graphics adapter supports and curpage contains the page that is currently being displayed.

G_info must be called after the display is opened with g_open . g_init(1), g_open(1).

unsigned card, display; The g_init function initializes the graphics library for the graphics card and display in use. If g_init is called with card set to zero, it will attempt to determine what graphics hardware is attached. The display parameter is ignored in this case and may be omitted. If card is one of the (nonzero) symbolic constants for graphics adapters defined in graf.h , the graphics library assumes that that card is attached. In this case, the parameter display must also be specified as one of the symbolic constants defined in graf.h .

This function must be called before any others. g_open(1), g_close(1), g_info(1).

int x1, y1, x2, y2; unsigned color; The g_line function draws a line in the current drawing buffer with color color between the points (x1, y1) and (x2, y2). If xor mode is on, the line is logically xor'ed with the existing data in the buffer. g_box(1), g_point(1).

unsigned mode; The g_open function switches the display to a graphics mode and prepares the graphics routines for drawing. The interpretation of the mode parameter is device-dependent. Currently, on the CGA, mode = CGA_640 is the 640 by 200 two color mode, and mode = CGA_320 is the 320 by 200 four color mode. The CGA_640 and CGA_320 constants are defined in graf.h . On the EGA, the mode parameter is ignored, and the display is opened in the 640 by 350 sixteen color mode using the Enhanced Color Display, the 640 by 200 sixteen color mode using the Color Display, and the 640 by 350 monochrome mode using the Monochrome Display. To use an EGA in a CGA mode, pass CGA as the card parameter to g_init .

Besides setting the graphics mode, the g_open function also clears the screen, resets the color mapping to the default, turns off xor mode and screen buffering, and resets the clipping boundaries to the physical boundaries of the screen.

This function must be called after g_init , and before any other graphics functions. g_init(1), g_close(1), g_info(1).

int x, y; unsigned color; The g_point function sets the point (x, y) in the current drawing buffer to color color . If xor mode is on, the point is xor'ed with the existing data in the buffer. g_line(1).

g_regfill — fill a rectangular region with a color void g_regfill(x1, y1, x2, y2, color)

int x1, y1, x2, y2; unsigned color; The g_regfill function sets all the points in the current drawing buffer within the rectangle defined by the points (x1, y1) and (x2, y2) (and within the current clipping boundary) to color color . Doesn't support xor mode g_clear(1).

unsigned color; The g_setback function changes the color displayed for the background color value (0).

The color parameter should be the value of one of the colors listed in the CGA background color table on the ``colors(1)'' manual page.

The color parameter is a six-bit color value as discussed on the EGA section in the ``colors(1)'' manual page. Doesn't work in the CGA two color mode. intro(1), colors(1), g_setpal(1).

unsigned flag; The g_setbuf function turns screen buffering on, if flag is nonzero, or off if flag is zero. When screen buffering is on, drawing takes place in an off-screen buffer, instead of in the buffer that is currently being displayed. This off-screen buffer can then be made visible almost instantaneously with the g_show function. This can be a great help in achieving smooth animation and other effects.

There is, however, one important consideration to keep in mind. For effeciency reasons, the g_show function is implemented differently on different graphics devices. On the CGA, the drawing is done in a single off-screen buffer which is then copied to the physical screen buffer when g_show is called. On the EGA, which has two display pages, drawing is done in the page that is not visible and the pages are swapped when g_show is called. This means that immediately after calling g_show on a CGA, the drawing buffer contains a copy of the image being shown on the display. But immediately after calling it on an EGA, the drawing buffer contains the image that was visible just before it was called. This difficulty can be avoided by the simple expedient of erasing the active area of the drawing buffer immediately after every call to g_show . g_show(1).

int x1, y1, x2, y2; The g_setclip function restricts drawing to the rectangular area defined by the points (x1, y1) and (x2, y2). Points that lie outside this rectangle (the ``clipping boundaries'') will be protected from change by any the routines that respect the clipping boundaries. The clipping boundaries cannot be set outside of the physical screen. The functions which respect the clipping boundaries are g_box, g_circle, g_clear, g_ellipse, g_line, g_point, and g_regfill .

unsigned palette, value; The g_setpal function allows one to change the mapping between the foreground color values passed to the graphics routines and the visible colors actually displayed.

The actual functioning of this routine depends on the graphics mode in use as follows:

The g_setpal function changes the color of the foreground color value (1). The value of palette is ignored, and value should be the value of one of the colors listed in CGA background color table in the ``colors(1)'' manual page. The visible color of the foreground will be changed to this color.

In this mode, the value parameter is ignored, and palette should be either 0 or 1. The displayed colors are given by the following table:

&color&value &background & &color value&& $\it palette=0$ & $\it palette=1$

&& 0 &background&background && 1 &green&cyan && 2 &red&magenta && 3 &yellow&white

In this mode, the g_setpal function directly sets the visible color of the color value given by palette to value , which is a six-bit color as discussed in the EGA section of the ``colors(1)'' manual page. intro(1), colors(1), g_setback(1).

unsigned flag; The g_setxor function turns xor mode on if flag is nonzero, or off if flag is zero. When xor mode is off, drawn objects are simply written over existing data in the drawing buffer. But if xor mode is on, drawn objects are logically xor'ed with the existing data. Thus if an object is drawn twice in a row in exactly the same position with xor mode on, it will be completely erased after the second drawing and the image on the screen restored to its state previous to the first drawing. This makes xor mode useful for animation and other effects. Functions which support xor mode are g_box, g_circle, g_ellipse, g_line, and g_point .

g_show — make the drawing buffer visible void g_show() If screen buffering is on, the g_show function makes the drawing buffer visible by either copying it to the physical screen buffer (on adapters with only one page) or swapping it with the currently visible page (on adapters with more than one page). If screen buffering is off, g_show does nothing.

See the description of the g_setbuf function for further discussion of screen buffering. g_setbuf(1).

unsigned row, col; char ch; unsigned color; int page; The g_writech function writes the single character ch at character position (row, col) with color color . If page is -1, the character is written to the current drawing buffer; otherwise it is written to page page (note: this is not supported with the CGA, as it only has one page). With the CGA adapter, the page parameter is ignored.

g_writestr — write a string teletype style void g_writestr(row, col, s, color, page)

unsigned row, col; char *s; unsigned color; int page; The g_writestr writes the null-terminated string pointed to by s starting at character position (row, col) with color color . If page is -1, the character is written to the current drawing buffer; otherwise it is written to page page (note: this is not supported with the CGA, as it only has one page).

The characters are written from left to right, top to bottom. If the writing goes off the right edge of the screen, it continues at the beginning of the next line. If the writing goes off the bottom of the screen, the function is aborted.

The only special characters recognized are newline (octal 12), which causes the writing to wrap around to the beginning of the next line, and carriage return (octal 15) which is simply ignored. With the CGA adapter, the page parameter is ignored.